Apple, the Apple logo, AppleScript, Bento, Macintosh, QuickTime, and OpenDoc are
registered trademarks of Apple Computer, Inc.
Finder, Mac, and QuickDraw are trademarks of Apple Computer, Inc.
SOM, SOMObjects, and System Object Model are licensed trademarks of IBM Corporation.
Continued from Part 1...
Posting a Link Specification to the Clipboard or Drag and Drop Object
When data is copied to the clipboard or drag and drop object, the part should usually write a link specification in addition to content. The link specification indicates to any part performing a paste or drop that a persistent link may be created to the original content, using any of the representations present in the kODPropContents property.
The data in a link spec is private to the part writing the spec. The data written to the spec will be returned to the part via its CreateLink method if a link is actually created. The part needs to be able to identify the selected content from the link spec data. Because the link spec is only valid during the lifetime of the part, the data can contain pointers to information maintained by the part.
This example shows adding a link specification to the clipboard. To add a link spec to a drag and drop object, just replace clipContentSU with the content storage unit of the drag and drop object.
linkSpec = myDraft->CreateLinkSpec(ev, somThis->fPartWrapper, link spec byte array);
linkSpec->WriteLinkSpec(ev, clipContentSU);
CATCH_ALL
ODReleaseObject(linkSpec);
RERAISE;
ENDTRY
ODReleaseObject(linkSpec);
When Not to Post a Link Specification
When copying data to a content storage unit, parts should not write a link specification in any of the following cases:
• The content storage unit belongs to a link source object, not the clipboard or drag and drop object.
• The part's draft does not have write permission. Before writing a link spec, check the draft permissions. If the permissions don't allow writing, a part should not write a link spec. Since the draft cannot be saved, the internal links cannot be preserved, and an external link created to another document will be abandoned when the draft is closed.
• The data is in a link destination maintained by the part.
• The part itself is embedded in a link destination (the link status of its display frame is kODInLinkDestination).
• The data contains only a portion of an existing link destination. The difficulty is maintaining the source link when the destination link is updated. It is in general impossible to determine what content the source link should assume when the destination changes.
• The data includes an entire link destination exactly. In this case, copying the content and pasting will create a another link destination if pasted into the same document (unless the user picks a lower-fidelity kind that doesn't support linking). If the part wrote a link specification and the new destination chose to create a link, an second link would be created between the existing and new destinations, probably not what the user wanted. The user should have to select the source to create a destination in another document.
Removing a Link Spec from the Clipboard
It is the responsibility of the part writing a link spec to remove it from the clipboard when:
• It becomes infeasible to create the link, for example, because the potential source content is deleted.
• The part's ReleaseAll() method is called.
In order to determine whether a link spec written by a part still resides on the clipboard, the part must remember the update ID of the clipboard when it writes the link specification. The following code fragment can be used to remove a link spec:
The settings and choices in the Paste As dialog rely on accurate information about the kinds supported by a part. See the document "Binding and 'nmap' Recipe" for details on how to specify the kinds supported by a part.
Implementing Paste with Link (Incorporating Content)
When the user chooses the "Paste As…" menu item, the part should call the ShowPasteAsDialog method of the clipboard or drag and drop opbject to display the dialog. If the ODPasteAsResult value set by that method specifies a link should be created to the source, this recipe should be followed.
Parts should enable the "Paste As…" menu item only if the draft's permissions allow writing.
Basically, the receiving part should ignore the content on the clipboard, and read the link spec value there using ODLinkSpec::ReadLinkSpec. The link object is obtained via the receiving part's draft's AcquireLink method. The receiving part should maintain an ODLinkInfo structure for the destination of the link, initialized from values of the link object and from the ODPasteAsResult value as set by the user.
Because pasting a link does not get content from the clipboard, your part should not call the clipboard's ActionDone method.
The routine MyPasteWithLink shown here takes three parameters. The first is the content storage unit of the clipboard or drag and drop object. The second is the structure returned by the ShowPasteAsDialog method of either the clipboard or drag and drop object. The third is a boolean indicating whether content is pasted from the clipboard or the drag and drop object; this makes a difference in how the routine adds undo actions.
MyPasteWithLink shows how the part performing the paste is expected to add undo history. Because link creation involves both the source and destination parts, an undo transaction is used to capture actions by both parts. If the link is being created from the clipboard, the destination must begin an undo transaction before calling AcquireLink. If the link is created during a drop, the part that initiated the drop is assumed to have already started an undo action, so this part simply adds its undo data as a single action.
Note that MyPasteWithLink will register for update notification even if the user has requested manual updates. Because cross-document links may be created asynchronously, its not always possible to read data from a link immediately. Registering for notification gives the source part a chance to deliver the data. When this part's LinkUpdated method is called, and content is available (i.e. GetContentStorageUnit doesn't return the error kODErrNoLinkContent), the part should unregister if the destination updates manually, and there are no automatic destinations of the same link maintained by this part.
For simplicity, translation of content incorporated through a link is not covered here. Examples of translation appear in the section “Embedding a Part via the Paste As Dialog” in the Data Interchange Basics document.
Any part that supports embedding and linking should allow the user to embed content from the clipboard and create a link. When content from a link is embedded, the destination part (the part performing the paste) does not clone the content storage unit of the clipboard or drag and drop object. Instead, the part reads the link spec from the content storage unit, acquires the link from the link spec, and creates an embedded part by cloning the content storage unit of the link. When the link is updated, the destination part discards the embedded part and creates a new embedded part from the new link content. The embedded part is not involved in the maintenance of the link. The link border appears around the embedded part's frame and is drawn by the destination part.
Because pasting a link does not get content from the clipboard, your part should not call the clipboard's ActionDone method.
When content is embedded, the user may choose a particular content kind or specify a translation to another kind. The Data Interchange Basics recipe "Embedding a Part via the Paste As Dialog" describes the steps the part performing the paste takes to embed the desired content kind. The recipe is directly applicable to embedding linked content; in this case, the content storage unit of the link is cloned (as above), and then any necessary translation is performed.
Drop Result when Pasting a Link
When a link is created using drag and drop, be sure your part's Drop method returns the ODDropResult value kODDropCopy.
Registering for Update Notification
The “Implementing Paste with Link” recipes demonstrate how a destination part can register with the link to receive automatic notifications when the link is updated with new content. When a new link destination is created, parts should always register to receive notification that the initial content is available.
Parts register for updates by calling the RegisterDependent method of the link method. The part supplies the update ID of the content it last read from the link. To get the initial content from the link, a part can use the update ID constant kODUnknownUpdate to ensure it receives notification. Parts receive notification of an update via their LinkUpdated method.
If a part's LinkUpdated method is called after registering to receive the initial content from a link, the part should unregister if the user specified that the destination should update manually.
Parts should register for notification when a part is internalized if the link updates automatically and the link is visible or may affect layout of the part. When your part calls RegisterDependent, its LinkUpdated method may be called before RegisterDependent returns, so be sure to call RegisterDependent only when your part is prepared to receive a notification. Parts may unregister and re-register for notification as they wish. However, parts must be careful to register only once with the same link, even if they maintain two or more destinations of the same link.
If a part is in a read-only draft, you may call RegisterDependent, but your part won't receive notification (your part's LinkUpdated method won't be called).
Undoable Actions and Linking
The following user actions involving links should be undoable (this list may not be exhaustive):
• Pasting content creating a link to the source.
• Pasting content containing existing links.
• Breaking a link at the source or destination via the Link Info dialog.
• Deleting a selected link and its content, or deleting content containing one or more source or destination links.
• Cutting content containing one or more source or destination links.
The updating of links, at the source or destination, is not an undoable user operation. A part updating the destination of a link does not have to create an undo action to restore its previous content. Similarly, a part updating a link from source content does not need to create an action state to restore the link to its previous contents.
When content containing a source link is removed by deleting or cutting, or when a source link is broken, your part should:
• save its reference to the link source object in undo action data and disassociate the link source from the content in whatever way is appropriate for the data format,
• call linkSource->SetSourcePart(ev, kODNULL); so the object no longer references the part.
Note that your part should generally not update a removed or broken link source with empty content; just leave the link source in its existing state.
If the action is undone, the part should:
• reinstate the link source object into your parts content,
• call linkSource->SetSourcePart(ev, somThis->GetStorageUnit(ev)); to reestablish this part as the source of the link.
If a link or link source is broken, your part must change the link status of any affected frames; see the section “Frame Link Status” later in this document.
Similarly, links may be broken at their destination, or they may be deleted or cut along with the content at the destination of the link. When this happens, your part should:
• save a reference to the link object in undo action data, and, if the link was explicitly broken, disassociate the link from the content.
• If this part is registered to receive update notifications, call link->UnregisterDependent(ev, somSelf->fPartWrapper) if this was the last automatically updated destination of the link in this part.
Your part should hold a reference to each link or link source objects in undo action data until the part's DisposeActionState method is called.
Undoing Operations involving Link Destinations
When designing and implementing undo and redo of operations that add or remove content, such as cut or paste, you must take into account the behavior of destination links in that content. Your part does not treat updating a link destination as an undoable action. When a link updates, your part removes the existing content at the destination, and replaces it with new content from the link. Your part does not create an undo action, and does not save the content that is replaced. After an operation is performed, but before that operation is undone (and possibly redone), destination links in the affected content may update one or more times.
As one example, consider the case where content containing a link destination is pasted. If the link destination is updated before the paste is undone, the content associated with the paste may contain different objects. If the user undoes the paste, your part must not assume the same objects that were created at the time of the paste are present. Your part must undo the paste with whatever objects are currently in place. In particular, the undo information your part associates with the paste should not include specific objects cloned from links.
Paste is not the only operation which can be affected by link updates before being undone or redone. In general, care must be taken to ensure that undo action data respects updates to link destinations. One approach is to maintain a content object representing each link destination, which acts as a proxy for the destination's actual content. This eliminates direct references to intrinsic or embedded content objects within the link destination from undo action data.
Accessing a Link
Because source and destination parts may attempt to access a link simultaneously, parts must acquire a lock in order to get the storage unit containing the content of the link. Many methods of classes ODLink and ODLinkSource require a valid link key that can only be obtained by successfully acquiring a lock first. Parts must not access the storage unit returned by GetContentStorageUnit after unlocking the link.
In the current implementation of OpenDoc for MacOS, Lock returns FALSE immediately if the wait argument is non-zero and the lock cannot be granted. In general, there is no urgency about updating links at either source or destination. (In fact, the HI Guidelines recommend that parts do NOT update source links for each atomic change in source content when the changes occur repeatedly without pause, such as when keystrokes are being entered.) The examples show passing a wait argument of zero to Lock(). If your part fails to obtain a lock, it can complete the link update later, for example by registering for idle time and attempting to obtain the lock during a future call to HandleEvent.
Basic Recipe for Writing to a Link
This basic recipe can be used to write the initial content into a link when created, and to update the link when the source content changes. This example routine illustrates the use of promises, which must be fulfilled by this part's FulfillPromise method. It uses the routine MyWriteToContentSU described in the Data Interchange Basics document.
To ensure that promises written into the link are fulfilled correctly, this routine adds a kODPropCloneKindUsed property before calling MyWriteToContentSU. In their FulfillPromise methods, all parts should check for this property to see if a clone kind other than kODCloneCopy should be used. When FulfillPromise is called to write to a link, BeginClone will fail with an inconsistent clone kind error if the clone kind is other than kODCloneToLink.
When the link is initially created or when its being updated, the justRewriting parameter should be kODFalse. If the part's CreateLink method is called to create another destination of an existing link, and the content at the source of the link hasn't changed since the link was last updated, the justRewriting parameter should be kODTrue. See the recipe for creating a link for more information on when to pass kODTrue to the justRewriting parameter.
The promiseData parameter is whatever information the part needs to identify the promised content when its FulfillPromise method is called.
The contentShape parameter will be written into the link in the suggested frame shape annotation. This property will be used as the frame shape should content be embedded at the destination of the link.
The partName parameter is passed thru to MyWriteToContentSU.
The Clear method removes the kODPropContents property from the link's content storage unit. After calling Clear, your part must call GetContentStorageUnit, add the contents property, write promise values (or actual values) into the link, and call ContentUpdated to notify destinations. After your part calls Unlock, OpenDoc will fulfill any promises for values that are used by destinations.
Note that the Clear and ContentUpdated methods of ODLinkSource will return an exception if passed kODUnknownUpdate as the argument to the update parameter.
void MyWriteToLink (Environment *ev,
ODLinkSource* linkSource,
ODUpdateID updateID,
ODBoolean justRewriting,
ODByteArray* promiseData,
ODShape* contentShape,
ODIText* partName)
{
ODVolatile(linkSource);
ODLinkKey linkKey;
ODVolatile(linkKey);
if ( linkSource->Lock(ev, 0, &linkKey) )
{
// Remember the previous updateID in case updating fails
// Clear a partially-updated link. Destinations must deal
// gracefully with a link content storage unit that has no
// contents property.
linkSource->Clear(ev, previousID, linkKey);
linkSource->Unlock(ev, linkKey);
RERAISE;
ENDTRY
linkSource->Unlock(ev, linkKey);
}
}
Implementing CreateLink
The creation of a link is initiated when the part performing a paste or drop calls its draft's GetLink method, passing in a link spec read from the clipboard or drag-and-drop container. A recipe for pasting a link appears elsewhere in this document.
A link is created by a part's CreateLink method. Any content kind written to the clipboard or drag-and-drop container should be available through the link. When providing the initial content for a link, a part may write either promises or actual data. By writing promises, a part can provide content for only the data kind(s) actually used by destinations of the link. When a destination reads data through the link, the source part will be called to fulfill its promise for a particular content kind. A separate document discusses promises in more detail.
This example implementation of CreateLink demonstrates how your part should add to the undo history when a new link source is created. The action will be added to an undo transaction (started by the part performing the paste, or this part if the operation is a drop). See the next section, "Better Undo Recipe for CreateLink", for the preferred way to handle undoing the link creation, although it is a little more work for your part.
CreateLink should only be called by drafts, not directly by parts. This example demonstrates how your part may implement its CreateLink method. It uses the routine MyWriteToLink to create the initial content of the link, using promises, and to ensure that all values are present each time an additional destination is created. If your part doesn't write promises to a link, the else-clause in this example can be eliminated.
// If the link couldn't be updated, CreateLink should fail rather than
// return a linkSource without a contents property.
linkSource = kODNULL;
RERAISE;
ENDTRY;
}
// The result of this method must be released by the caller.
linkSource->Acquire(ev);
SOM_CATCH_ALL
SOM_ENDTRY
return linkSource;
}
Better Undo Recipe for CreateLink
If your part implements undo support as described in the recipe above, and the link is created via cross-document drag and drop, the undo action stack will contain two separate undo items; one for the drop, and another for the creation of the link source. There are two undo items in this case because the call to the source part's CreateLink method is postponed until after the drag completes and returns to the source part.
Your part can avoid introducing a second undo item in this case by doing the following. When you write a link spec to a drag and drop object's content storage unit, include in the part data information identifying the undo history transaction your part created for the drag and drop operation. Then, in your CreateLink method, check for this information, and instead of adding an undo action as described above, modify some private data your part associates with the drag and drop undo transaction so that the link creation is undone (or redone) as well.
When CreateLink is called to get an existing link
CreateLink may be called multiple times with the same link spec to create multiple destinations of the same link. If your part writes actual content into the link, it can just return the link object. However, if your part writes promises, it must ensure all values are available in the link.
If CreateLink is called to get an existing link, its important that the link contain all value types available via the clipboard or drag and drop object. If a part writes promises into a link, the link will contain only actual content used by current destinations; if the draft is saved, unfulfilled promises will be removed. When CreateLink is called, the part must ensure that at least a promise is present for all value types. A part can handle this as shown in MyPartCreateLink above.
Parts can now use the Clear method to replace promises in a link without notifying existing destinations. Clear may be called with the existing update ID; by not calling ContentUpdated, destinations won't be notified (as shown in MyPartCreateLink). If ContentUpdated is called with the existing update ID, the circular link update alert will appear.
